Power Tools for Macintosh/Power Tools for Macintosh (SoftBit)(1992).iso/Applications/Mark My Words/That Manual Thing

Text File | 1993-06-30 | 58KB | 1,240 lines

That Manual Thing

(Mark My Words - at last!)


Documenting: Mark My Words (version 1.0.0) © 1993 by Greg Swann


6/24/92


Greg Swann

CompuServe: 70640,1574

USPS: P.O. Box 1724
      Andover, MA 01810

      or

      1331 West Baseline Road, #236
      Mesa, AZ 85202



Table of Contents

0. Blah, blah, blah...

1. Introductory chatter...

2. Commercial, legal and other pertinent notices...

3. Using Mark My Words: the big picture...

4. Where the bodies are buried...

5. Gloats and flourishes...

6. Mark My Words in real life...

7. About Greg Swann...

8. Conclusion...



0. Blah, blah, blah...

"You can rest when you die."

            - Charles Barkley

That's been my motto though this last round of development, and I've
had occasion to refer to it more times than I expected.

Here's the story: we started this a _long_ time ago. Shane Stanley,
uncompensated Vice President in Charge of Everything Else, had
asked Chris Ryland of Em Software to write an MS-Word filter for
QuarkXPress that would parse the Word binary _and_ parse any XPress
Tags found in the text. Chris declined, proving himself possessed
of the better part of valor. Having exhausted the pool of talented
talent, Shane turned to me, undercompensated Vice President in
Charge of Nothing But. I wasn't interested in writing an Xtension,
but I did sign up to do this piece of software, Mark My Words.

But: I knew at the time that I didn't know enough to do it. Parsing
someone else's binary and living in peace with three other pieces
of software was, I felt, a bigger chunk of reality than I wanted to
tear off at the time. That's why we did WordLess Plus, a game if
lame pretaste of what we have here (WordLess Plus is FreeWare and
is available in the DTPForum on CompuServe (as WLPLUS.CPT) and
other services; from now on I'm just going to give the CIS file
names, since the vectors don't change).

After that, we set about acquiring the skill set I knew we'd need
for this: With Clip 'n' Save (C&S.CPT) we played with PICTs. With
Lizzie Borden (LIZZIE.CPT) we worked out a way to soak up and spit
out text very quickly. With Shane the Plane 2.0 (SPDEMO.CPT) we
explored sensible, intelligent Drag & Drop strategies.

There was other stuff in there, including upgrades to XP8 (XP8.SEA)
and Torquemada the Inquisitor (TORQUE.SEA), quick diversions like
ShawBerry (BERRY.CPT), PixPex (PIXPEX.CPT) and A Sort of a Kind
(ASOAK.CPT), plus the normal crush of making a living. Finally in
December we got busy, completing the user interface and slamming
away at the action routines.

We started with WriteNow 3.0 files, which we had planned to support
in Mark My Words. We had to stop around Christmas for a couple of
big contract jobs and by the time we popped MMW back off the stack,
WriteNow had been sold to KissOfDeathWare (publishers of
WordStarYouKidding?) and was selling for $37, bundled with 57 fonts
and a golf game, slugging it out for shelf space at K-Mart.

Oh, well...

Then we moved to Arizona.

Best thing for us, but it cost time. Anyway, to make a long story
interminable, it took us a while to get started even after we were
ready to begin. Then it took _forever_ to finish.

None of this is such a terrible thing. The whole long while we were
not doing this, we were learning how to do it, even when we weren't
looking for lessons. Most of my early stuff derives from XP8 and
Torquemada. Most of my recent stuff draws upon Lizzie Borden and
Shane the Plane 2.0. But there is code in here from IntelliStudy,
one of the contract jobs, which you will never see unless you pay a
lot of money to take a bar review course. And even once we
(re)commenced, we learned a lot. Not all of the lessons were
pleasant, but all of them were valuable.

I tend to write very incrementally. Where another programmer might
devote 20% of his time to coding, and the rest to debugging, I
(normally) spend 95% of my time coding and debugging iteratively
and 5% debugging after the fact. Total investment of labor is
probably about the same, but I feel my way maximizes the
satisfaction and minimizes the frustration.

Unfortunately, it didn't quite work this time. We hit a Word
anomaly late in the test cycle and lost a week trying to find and
fix it. It seems trivial when looked at from the back, but there
was a span of time where I was convinced we were going to have to
disable a key feature. Not cool. Not fun. Not timely in a product
that was already _very_ late.

And, to compound all this, Mark My Words has a large pre-sale.
People have had their money in my bank account for many months,
which, I'm sure, has not been fun for any of us.

Well, all that's past. The Phoenix Suns have been in the NBA
playoffs as we've been finishing this and - no causal connection,
obviously - we've hit major milestones at about the same times. The
outcome of the finals is still in doubt as I write this, but we
take our cue from #34, power forward and MVP, Sir Charles Barkley:
"You can rest when you die."



1. Introductory chatter...

Okay, so what is this...?

Mark My Words is a very elaborate MS-Word binary to XPress Tags
text filter. It eats Word 4.0, 5.0 or 5.1 files, interactively or
by Drag & Drop, and converts the binary to QuarkXPress tagged text.

Answering the question: why?

* The Word filter that ships with Quark would be half-witted with a
little more schooling. No beef, really, they're doing the 80% job
that one can expect of an import filter. But Mark My Words converts
100% of everything that can be produced in Quark, converts it
intelligently, and gives the user a very high degree of control
over the conversion, permitting, for example, the omission of
unwanted styling or the conversion of word processor-like styling
to desktop publishing-like styling.

* Word has the potential to be an excellent "Story Editor" for
Quark but for this: if you Save Text from XPress in Word format,
you lose a _lot_ of styling Quark can produce but Word cannot. But
if you save as XPress Tags, then edit in Word - _using_ Word
styling such Cmd-Shift-B - then run it past Mark My Words, you
retain all the original styling and all the new styling, plus you
acquire the ability to do corrections in a familiar way with
familiar keystrokes.

* Moreover, when drafting, you can key in XPress Tags constructs
for features that Word does not support. For example: you’re using
oodles of drop caps, and you’ve set up the styles the way you want
them in XPress. But you really want the drop caps to be scaled 80%
horizontally. Before, you had to either do the scaling in XPress
(inconvenient), or do all your styling with tags (mind-numbing).
Now you can do all your normal styling the Mac-way, and just throw
a <h80> and <h100>  around your drop caps. Mark My Words will do
the rest.

* Most significantly: converting the file to a text form with all
styling retained permits you to massage the text with Word, another
editor, or one of my text-banger utilities like ShawBerry or
Torquemada. If you import with the Word filter, you keep the
styling - even where it's bad - plus all the crap. With Mark My
Words, you can omit or convert the styling and you end up with a
file that can be cleaned up with very efficient tools. Moreover,
the new file can be run as is through XP8 to get a massive amount
of quality improvement for a negligible investment of labor.

Better filtration. Easier, faster editing. Infinitely better
quality. Win, win, win - surely a better way of working...

As mentioned above, Mark My Words owes its origin to Shane Stanley.
He wanted a way to work in Word and yet gain access to XPress Tags.
At first I wasn't too sanguine about the idea, but I've learned to
respect Shane's hunches. I wasn't all that hungry for the ability
to style the Macintosh way, first because I don't create a lot of
text for publishing, and second because I'm used to styling the
text I get from clients directly in XPress Tags, using Torquemada.
The bad part about doing things that way was that I was losing the
italic and bold styling that the clients put into their files,
which was a big pain. So despite my doubts, I was way sold on the
concept after we finished WordLess Plus. I could keep what I wanted
and throw away the rest.

From the get, we knew we wanted to support Em Software's Xtags.
Xtags is a plug-compatible XPress Tags filter that offers a rich
superset of the XPress Tags commands. It is highly recommended to
Power Users of QuarkXPress. In MMW, we are supporting Xtags'
ability to create in-line text and picture boxes in a tag stream.
The advantage to this is, if you own Xtags, you can retain any
pictures or in-line tables that are in your Word files.

One of the original design goals was to permit iterative re-editing
(that is, taking a Word file, putting it through MMW, cleaning it
up, then doing additional edits back in Word, continuing to use
Word's styling commands, then putting it through MMW _again_, to
convert the added styling). WordLess Plus supported this after a
fashion, but Mark My Words does a much better job of it.

And: Shane wanted a way to insulate himself and others from bad
selections when editing. Suppose you have a Word file with explicit
tags in it, typed or inserted by Mark My Words, and you mis-select
some part of those tags and change the styling. For example, you
have:

<I>Lepton Local<I>

and you decide to make the title of that fine piece of software
Bold-Italic instead of just Italic. You mis-select, making this
much of the text bold:

>Lepton Local

If Mark My Words were not watching for exactly this kind of error,
you would get:

<I<B>>Lepton Local<BI>

which would choke the XPress Tags filter and elicit a nasty note
from Xtags.

Such deep thinkers are Shane and I that we've been pondering this
problem since MMW was a gleam in Shane's eye. Instead of the
erroneous tags above, MMW will produce:

<I><B>Lepton Local<BI>

No extra charge.

Finally, Shane and I went through about a bazillion rounds of User
Interface development. What we wanted was a UI that would permit
Power Users to take control over every little last thing but would
not present a dizzying array of choices to users less frenetic in
their pursuit of the arcane. I'm very proud of the results, and I
wish to thank Shane publicly, as so many times before, for the
gentle pushing he does in behalf of end-users (starting with
himself, of course (grin), but good products are made by designers
who are also hungry users).

I can't say enough good things about Shane, but I'll never stop
trying. If there's anything you hate in software by me, blame me.
But for anything you love, you can expect that at least part of the
credit owes to a light on in a house - and a mind - in Nar Nar
Goon, Victoria, Australia.

Mark My Words was tested by Shane, Mary Jo Kostya, Kip Shaw, Mike
Arst, Brad Walrod and Chris Ryland. Shane, Mary Jo and Kip were the
chief victims of the terrible anomaly found late, since it affected
only 68040 machines; think about this when you hear the Clintons
claim that the rich get a free ride (grin). This manual was looked
over by Shane, Mary Jo, Kip, Mike and my dear wife, Ann Swann. None
of them should be held accountable for any part of it, of course,
since I always do what I want, despite excellent advice to the
contrary.

On the subject: this file is written as plain text in DOS-like
fashion (i.e., every line ending is a carriage return). It is
produced in a FreeWare Programmer's editor called BBEdit by Rich
Siegel (which is recommended). I've had mail about this, so I'll
explain: I produce documents this way because doing so makes no
presumptions about what software and fonts you might own. _Most_
word processors can open, e.g., MS-Word files. But _all_ word
processors can open _this_ file.

The original FreeWare WordLess Plus is available and will always be
available for free. But: Mark My Words is commercial software: you
can't use it (for long) without paying me. The copy of Mark My
Words in this archive is a DemoWare version that will permit up to
32 launches and then forevermore refuse to do anything but be an
automated salesman. It is a _fully functional_ demo. Nothing is
crippled. A little bit of advertising is tacked on at the end of
each file, but everything works exactly as documented here. The
only inhibition is the one named: 32 launches, max. See
"Commercial, legal and other pertinent notices" below for
information on how to purchase unrestricted copies of Mark My
Words.

TechnoBabble: Mark My Words is compatible with both Systems 7 and
6. It is AppleEvent-aware, so, presumably, you could script to it.
It's 32-bit clean, MultiFinder-aware, doubles on sax (turn up the
volume!), leaves no filmy residue on your fine china - all the
usual stuff. In short (there will be much more later), it's
everything you expect of up-to-the-microsecond Macintosh software.

And: this manual presumes a certain adeptitude with QuarkXPress
and, especially, XPress Tags (if you’ve never used them before,
take a look at Appendix C in the XPress manual). But to benefit
from MMW, you need only a basic understanding of how tagging works.

If you've been following my meteoric rise to obscurity, you know
that I'm an XPress Tags fanatic. If not, some explanation is due:
XPress Tags is a Text Only language built into QuarkXPress (since
version 3.0) that permits Quark to express and interpret almost
everything it can do. As such, it is richer than any other file
format Quark can import, and, hence, it allows users to do far more
styling and clean-up using automated tools such as my own
Torquemada and XP8. If this sounds like the "bad old days" to you,
you're right - it is. XPress Tags is a mark-up language, exactly
like those used in mainstream type systems and dedicated word
processors. But: in this one case, things were better when they
were worse. If you get a file that uses multiple spaces to
pseudo-align columns, you can spend all afternoon selecting those
space and typing tabs, or you can feed the file to XP8 and do the
whole job plus a lot more in 30 seconds. If you want to get really
radical with XPress Tags (not necessary to the use of Mark My
Words, but potentially very useful in your daily work), a good
place to begin is David Blatner's "The QuarkXPress Book" (Peachpit
Press).



2. Commercial, legal and other pertinent notices...

As mentioned above, this is a DemoWare version of Mark My Words,
fully functional but limited to 32 launches. The full unrestricted
commercial release can be obtained from Greg Swann at:

    P.O. Box 1724
    Andover, MA 01810

    or

    1331 West Baseline Road, #236
    Mesa, AZ 85202

Licenses are sold per machine, with a single license costing $50;
2-10 licenses are $45 each; and 11 or more licenses are $40 each.
(Write me if you want to negotiate an unlimited site license.)

I've thoughtfully (grin) provided a TeachText order form with this
archive. (Take note that this order form requires a PICT-aware
version of TeachText; use the version that came with your System
software, or open the file through some other PICT-aware software
(such as PhotoShop or MacDraw).)

Why is this version DemoWare? As with everything in my life, there
is philosophy here: I don't like crippled software. I don't think
much of ShareWare. And I almost never buy "a pig in a poke". In
deciding on a marketing scheme, I looked for something that would
be most appealing to _me_, were I in your shoes. This is what I've
come up with: a fully functional demo that lets you _find out_ if
Mark My Words is a useful tool in your working environment. If it
is (and obviously _I_ think it will be), then pay me. If it isn't,
then ditch it when it starts to offer to make coupons for you as a
full-time gig. A good deal all around, I think: no guilt for you,
no guilting for me; maybe useful software for you, maybe useful
money for me (grin).

(For those who must have it both ways: it would certainly be
possible to download this archive again and again, just to get
access to more launches. Even cleaner, a determined thief could
keep a pristine copy and spawn duplicates to use until they're
exhausted. My take on this is simple: so be it. I work _very_ hard
on the things I make, and I don't want to think that my labor is
going to support people who are overtly hostile to the life of the
mind. But I certainly don't want to be _compensated_ for that
unintended outcome. I may not get my due _from you_, but nature is
just: in the long run, I'll get what's coming to me - and so will
you.)

(And if this is the first time you've read a software manual by me:
you'll get used to it... (grin))

Mark My Words, its source and executable code, and this poor excuse
for a manual are Copyright (C) 1993 by Greg Swann. All rights are
most emphatically reserved.

The unrestricted (non-DemoWare) version of Mark My Words is
licensed for use on one machine by the person who paid for it. If
you didn't pay for it, please do! I am one person, with a
long-suffering family, not Conglomerated MegaSoft (not to imply
that there's any virtue in ripping _them_ off!).

Mark My Words is delivered "as is", without any warranties,
expressed or implied. It is not warranted to be useful _to_ anyone,
_for_ anything, and in no wise am I to be held responsible for any
unfortunate consequences resulting from its use or misuse. And I
_hate_ having to say things like that. I do my best to write
useful, simple, elegant, bug-free solutions to difficult problems.
If you take it into your head that I represent your big chance to
"strike it rich", you will pay a lot in legal fees to discover that
you have miscalculated.

And: to those to whom the above disclaimers do not apply: forgive
me for having to make them. It's _you_ whom I'm working for, for
pay or for free. I appreciate your patronage and your support, and
I wish we all could just comb the others out of our hair...

(Hey, it's a real 'personal' software company! (grin))



3. Using Mark My Words: the big picture...

Mark My Words works on batches of files by Drag & Drop (under System
7) or interactively from its main dialog (the Open... button). Drag
& Drop operation is relatively smart. In practice, the program will
only stay resident in memory if you are demonstrably interacting
with it. If you are doing no more than D&D batches, it will quit at
the end of each batch. Works like this:

D&D only: Quits

Double-click launch, then D&D: Quits

Double-click launch, then Open...: Stays resident

Double-click launch, hit any setting/menu, then D&D: Stays resident

We did it this way so that, if you are making temporary changes to
settings, you can still D&D, _but_ if you are just doing a D&D
batch (the likely normal procedure), MMW will get out of memory
without any effort on your part (nothing worse than having to Quit
from a bunch of small things to permit PhotoShop to launch).

Whatever the current state of your settings, you can get a Text
Only translation by holding down the Option key at the time that
execution begins. With the Open... button, you would hold down
Option as you hit the button. With a D&D batch, you would hold it
down as the batch begins. The override of the settings will affect
only that file or batch.

Mark My Words has a very large footprint in memory. Every major
decision came down in favor of speed, so we are consistently
trading memory for speed. The consequences are these: MMW is
_substantially_ faster than WL+, even though it's doing a _lot_
more; and it eats memory in big bites: the minimum memory required
is approximately 384K + (sizeOfFile * 4). We ship with a 768K
default, which is adequate for most files. If a file is too large,
you'll get an Alert telling you how much to allocate.

The Preferences menu is familiar to anyone who's used anything
recent by me. "Restore defaults" restores all controls to their
"factory" default settings. "Restore saved prefs" resets all
controls to their state at the last time the preferences were
saved. And "Save preferences" saves the currently established
settings; these are the settings that you will see with subsequent
launches and after you hit "Restore saved prefs".

Where appropriate, CMD-C (Copy), CMD-X (Cut) and CMD-V (Paste)
work, even though there is no Edit menu.

The settings in the dialogs are fairly self-explanatory. Everything
is driven by the pop-ups in the Mark My Words Settings dialog box.
Operations can be controlled in a gross fashion with the pop-ups,
and, where appropriate, finer adjustments can be made in
sub-dialogs.

The Output format pop-up is interesting. Text Only is obvious.
XPress Tags is also familiar enough. But we are also, optionally,
parsing to Em Software's Xtags, a superset of XPress Tags. The
effect of other switches within the dialogs will depend on the
state of this pop-up. For example, if you have Retain Pictures
checked, embedded pictures will be saved to disk. If you are
writing XPress Tags, it will be up to you to get those pictures
into Quark. But if you are writing Xtags, we're plugging in Xtags
coding to embed the picture in the stream. (Necessarily, pictures
are never other than PICTs (i.e., RIP-crashers), because that's all
that Word will store; they are named intelligently
("YourFileName¶001", etc.) and live in the same folder as the
_original_ Word source file; with Xtags, the size, scaling, and
aspect ratios are maintained, but you are advised to examine them
to make sure they'll fit in your text link.)

In the same respect, the effects of tables and other in-line
elements depend on your choice of formats. With Xtags, we are
doing as much as possible to maintain the original coding. As
above, you'll need to make sure that things fit.

And: this may seem like overkill, given that most people don't use
these features of Word. They're included because: 1. some people
_do_, and 2. given that we now have a convenient way of doing this
stuff (by means of Xtags), it seems reasonable to suppose that
we'll find ways of taking better advantage of these features. For
example, Word's multi-cell tables, in conjunction with Xtags and
Torquemada, give us a way of producing side-by-side tables such as
we haven't seen in a while. (Take note that this feature is not
supported by Quark's Word filter.)

IMPORTANT: a Word file converted by Mark My Words to Xtags will
choke the XPress Tags filter and vice versa. In theory, these two
Xtensions are identical except for the Xtags extensions to the
XPress Tags language. In practice, there are subtle differences,
with the result that an MMW file written for one filter will not be
compatible with the other. Not such a big deal: you just have to
remember to use the filter you selected in MMW.

Output file type enables you to select the creator type of the TEXT
files MMW will produce. This is one of those features that's more
icing than cake, in my opinion. It means that you can double-click
on a file created by MMW and have your editor of choice launch,
instead of Mark My Words or the editor of _my_ choice (BBEdit).
But: given that we live in the age of Drag & Drop (don't we?),
double-click access to your editor is less vitally necessary than
it was under System 6.

The Style sheets pop-up lets you control how much of Word's style
definitions go out to the new file. Include definition writes out
the full definition at the start of the file with any
omitted/unsupported values omitted, which means they'll default to
Quark's values for the BasedOn style. We surmise that people can
have changed their default Normal in Quark, and, moreover, Normal
can't be redefined from tags. So when we Include definition, we are
showing Word's Normal as WordNormal=[S"Normal"]. That way, if there
are exceptions to Word's Normal, they'll be preserved in the
definition when the file gets to Quark. And if you've made changes
to Quark's Normal, those will be retained where they are not
overridden by exceptions in WordNormal. Note that all other styles
BasedOn No Style continue to be BasedOn No Style. Also: when we are
defining styles, we don't know yet if that style is actually used
in the text. So all defined styles are shown, and you may want to
chop some out prior to Getting Text.

Include name shows only the name of the style as it is called in
the text. This is the one to use if you want to retain Word's
naming convention, but expect to write all the style sheets in
Quark (which policy is recommended). In this instance, Word's
Normal is shown as Normal (i.e., BasedOn No Style), since there are
no exceptions to preserve.

All to normal ignores all style definitions and calls and simply
shows everything in the Normal style (which is either Quark's or
your own edited default).

Ignore completely ignores styles, period. Use this when you have
edited a previously Marked file and want to leave the styles alone.

The next three pop-ups are where the bullet hits the bone. And they
demonstrate rather nicely, I think, why Shane and I deserve to win
the award for User Interface design of the year (grin). What's
going on is this: by means of these pop-ups, you can effect either
wholesale or retail control over the conversion. "Retain all",
"Retain defaults" and "Omit all" are wholesale controls, while
"Custom settings..." permits you to tailor the conversion to your
needs and tastes.

This is slick and quick. It keeps the number of choices in the main
dialog to a manageable minimum and gives less-experienced users a
lot of control without requiring a lot of hirsute knowledge. But
there is more at work here: we are actually storing and accessing
the settings in two ways. If you go into a "Custom settings..."
sub-dialog and make some changes, then hit Okay, then change that
pop-up to "Retain all", then "Save preferences", what will happen
is this: both the settings in "Custom settings..." and the state of
the pop-up will be saved as preferences for future use. When you
convert a file, the state of the pop-up ("Retain all") will be
honored, but the settings you established within the "Custom
settings..." sub-dialog will persist, ready for easy access with
the pop-up when you need them. There's a similar kind of speed-up
going on _inside_ the "Custom settings..." sub-dialogs by means of
the "All on", "All off" and "Prefs" buttons. Mark My Words is very
fast at doing its job, converting Word files to Tagged text. But
it's also designed to be very quick in its User Interface.

This is global information about the effect of the settings for the
"Paragraph styling", "Character styling" and "Ancillary coding"
pop-ups:

Retain all treats all check boxes as checked, treats all pop-ups as
though the second selection were picked, and enables all text edit
regions as their current settings. Retain defaults uses the factory
defaults, which is what you see if you Restore Defaults then
examine "Custom settings...". "Custom settings..." presents a
dialog in which you can change things to your liking. Omit all
treats all check boxes as unchecked, treats all pop-ups as though
the first selection were picked, and ignores the contents of the
text edit regions.

Within a "Custom settings..." sub-dialog, the "All on" button
treats all check boxes as checked, treats all pop-ups as though the
second selection were picked, and ignores the text edit regions.
The "All off" button treats all check boxes as unchecked, treats
all pop-ups as though the first selection were picked, and ignores
the text edit regions. The "Prefs" button resets all controls,
including the text edit regions, to their state when "Save
preferences" was last selected.

Repeating: the custom settings are honored _only_ if the "parent"
pop-up is set to "Custom settings..." If you make changes, hit OK,
then select Retain all, the custom settings will be preserved but
ignored during conversions, with the Retain all settings being used
instead.

The "Paragraph styling: Custom settings..." is the simplest of the
bunch: L&R indents, Leading, Alignment, Space before/after, Keep
w/next, First Line indents, and Tab settings are all obvious.

Important note about tabs: Word stores up to 50 tabs positions per
paragraph, while Quark stores only 20. One Word tab (the vertical
bar) can't be coded in Quark, so that saves us some slots. But:
when we get to the 21st tab we're done; no others are (or can be)
preserved. Moreover, the XPress Tags filter (as of version 1.5)
inadvertently throws away the 20th tab, so, in effect, with XPress
Tags (as of this writing) you have only 19 tabs; with Xtags, you
have the full 20.

For Keep together we are ignoring Word, which asks for <*ktA>, and
showing <*kt(2,2)> instead; the change reflects the difference
between word processing and desktop publishing.

Rules/Borders is a mutant: it's based on the Borders style in Word.
If a Border is established in a style's definition, we are showing
it as either a rule above and/or rule below, which means that the
rule(s) will show up in every paragraph in that style; nothing we
can do about that, since it comes with the style. However, when a
border is specified as an exception, we are showing the rule above
only above the first paragraph affected, and the rule below only
after the last paragraph, thus simulating as much as possible the
effect of the box in the original file. Since Word users can be way
stupid with boxes, and since, most often, their emphasis is
entirely redundant, my advice is to turn this off. At best, it
flags paragraphs thought worthy of emphasis by the WP operator.

There are a few things to discuss in "Character styling: Custom
settings..."  Style changes, Size changes, Font changes, and Color
changes are obvious.

The encapsulated font look-up table is used with Word 5.x files, so
you'll get true font names even though the fonts may not be loaded
or their numbers may be different. The font procedure for 4.0 files
is the same as that documented with WL+ - local system name if
fontID is loaded, fontID as text if not; that's what there is to go
by, alas.

The colors are the same brain-dead colors as in WL+ - nothing for
it, since that's all the colors there are.

Tracking changes: we're preserving this, but it's less than
perfectly useful. Word "tracks" with absolute values expressed in
quarter-points, range -7 to +56 quarter points. Too big for small
sizes, too small for big sizes, too stupid for words. We are
translating quarter points directly to Quark relative units. This
is not always awful, but it does always require follow-up scrutiny.

Super/subscript are translated Greg's way: <V> or <V->, IOW Superior
or Superior/Subscript. This seems to me to work better than Quark's
Superscript and Subscript styles, which I find to be too horsey,
and which frequently crash with the lines above and below. I have
my preferences set this way: 33% offset and 50% horizontal and
vertical scaling. Word uses pseudo-sub/superscripts in places
(e.g., footnotes referenced by text instead of counters), and these
are treated as any other styled text (which is what they are).

In the pop-ups: Hidden text: Omit throws it away. Retain retains
the Hidden text as text, with no additional styling. Shade 0%
retains it shaded 0, the way WL+ did it. Strike-thru retains it in
the </> style. This option is there for this reason: Word's Table
of Contents and Indexing tools use Hidden text, of course. If you
elect to retain these features, you need some way of getting at the
hidden entries. </> is a very uncommon styling option (with good
reason!), so I selected it as a way of flagging this stuff. Why? I
have hopes that some enterprising Xtension developer will take
advantage of this free mark-up to write TOC and Indexing for Quark.

The Underlines conversion is pretty straightforward. Word has four
types of underlines, while Quark has only two. The deficit is
hardly to Quark's disadvantage - when was the last time you had a
burning need for a dotted underline? In any case, each of Word's
underline types can be either Ignored (i.e., passed as plain text),
converted to Italic, converted to the Underline style, or converted
to the Word Underline style. By default, Mark My Words converts all
of Word's undlerlines to Italic, since this is usually what is
meant (in DTP terms) by underscored text.

Ancillary coding... is where the rubber meets the road. You may be
asking yourself, "Why all this damned UI?" The reason is this: if
you know what you're doing, you can control every little last
thing. If you don't, we're trying to make it easy for you to stay
out of trouble. Ancillary coding... is the home of the stuff that
it's fairly dangerous to play with (grin).

TOC entries and Index entries are discussed above. These switches
control whether or not the Contents and Index subdocuments and the
Index/TOC markers (".i.", ".c.") will be emitted into the text
stream.

Page breaks allows or disallows page breaks (expressed as <\c>) in
the text, including the Page Break Before styling command.

Headers/Footers controls whether or not these subdocuments will be
emitted into the text stream.

Date/Time entries permits or forbids the insertion of text
translations of Word's date/time variables. If checked, the dates
and times will reflect the time of the conversion. This feature
takes account of your current Control Panels settings for dates and
times, so, presumably, they'll be dancing in the streets of old
Budapest tonight...

Footnotes allows or disallows inclusion of the footnotes
subdocument. Calls to footnotes in the text will remain, as is, in
the text.

In-line pictures is Xtags coolness #1. If there are pictures in the
file, if this box is checked, and if the output format is Xtags,
the pictures will be saved to disk as PhotoShop PICTs and the
appropriate Xtags coding will be plugged into the text. If the
format is XPress Tags, the pictures will be saved to disk, but the
user will be responsible for placing them. Equations made with
Word's equations editor are encapsulated QuickDraw PICTs, which
means they can be edited with a QuickDraw editor like MacDraw or
Canvas, and they will produce device-independent, object-oriented
images. Likewise, since PICTuresque can create PICTs with
encapsulated PostScript, this feature is at least slightly more
than interesting window dressing (grin).

In-line text boxes is Xtags coolness #2. This controls what happens
with Word's in-line tables and Word 5.1's (incredibly stupid) drop
caps. If checked, if Xtags, in-line text boxes will be parsed into
Xtags boxes with the appropriate coding. The boxes are sized
arbitrarily, so you'll either have to drag them out by hand or
write Torque sets to change them. If not Xtags, in-line text is
emitted as styled text. In the case of tables, cell and row
boundaries are flagged with tabs.

MMW comments inserts readable comments into the text, where
appropriate, if a feature is turned off. For instance, if Date/Time
entries is turned off, and a date is found, the text "{{Date}}" is
inserted at that spot. If you don't want comments inserted, uncheck
this box. This is the list of possible comments:

{{Table cell}}

{{In-line box}}

{{Picture: NameOfFile¶000}} <-XPress Tags

{{Picture}} <-Text Only

{{Date}}

{{Time}}

{{Page number}}

{{Footnote separator}}

{{Footnote continuation}}

{{Formula}} <-refers to formula glossary text not equations

Many of the Ancillary coding switches, including MMW comments, have
meaning even in a Text Only translation. For example, if Date/Time
entries is checked, then the dates and times will be converted. If
not, but MMW comments _is_, then the comment will be inserted. IOW,
Text Only means what it says: any controls that would create new
XPress tags are disabled, but the others remain in effect unless
explicitly switched off.

Below all this are two text edit regions, one for the default
XPress Tags version tag, which is also honored by Xtags, and one
for the default Xtags translation table. Note that either of these
can be "switched off" merely by deleting the text. Note also that
each, if present, is inserted anew into a file, each time it passes
through Mark My Words. So, if you mark a file, then take it back to
Word for further editing, then mark it again, the old version and
Xtags &tt2 tags will be ripped out and replaced by whatever is the
currently established default. FWIW, while the version tag for 3.2
will be 1.6, MMW is writing XPress Tags 1.5/Xtags 1.0 compliant
tags. Filter 1.6 offers very little new coding, and most of it is
not relevant to Word. The only 1.6 construct in MMW is
[S"BasedOnStyle","NextStyle"], used only in XPress Tags
translations. Filter 1.5 ignores this construct, but filter 1.6
will accept it _if_ your version tag is set for 1.60.



4. Where the bodies are buried...

* I wish I had greater control over the in-line text boxes. I was
compelled to use arbitrary box sizes because of the idiotic way
Word stores the sizing information.

* The formula glossary text is far from ideal, largely because Word
is interpreting formulae on the fly (and has a lot of positioning
controls Quark doesn't have).

* The Rules/borders solution is the best answer we could come up
with to an ugly problem.

* As regards running the same text through MMW more than once, the
feature is robust but not fool-proof. If you're just doing text
editing, set Style sheets to Ignore. Any character or paragraph
property exceptions you introduce will be honored, but the style
sheets won't be parsed. If, OTOH, you want to define new styles,
you can. Just Include definition. Take note, however, that
WordNormal and any other default styles you have defined (i.e.,
present in all new documents) will be parsed again. You'll need to
go through the styles and chop out the replacements. This is
important because Quark does not redefine styles; the first
definition found for a particular name is the one used, and later
definitions under that name are ignored (this, essentially, is why
you can't redefine Normal).



5. Gloats and flourishes...

* Word, like Quark, is massively redundant. We are watching what
we're doing as we work and we issue styling only where an actual
change has occurred. No harm comes of writing extremely redundant
Tags, as does the QXPTags export filter, but doing it this way
makes things a lot easier on us wetware types.

* If you've used Quark's Word filter, you know that Quark and Word
do not agree about what happens to character styling at style
boundaries. Word retains the exceptions, while Quark wipes the
slate and baselines everything to the style. Taking account of this
conflict, Mark My Words reissues any pending styling exceptions
when a style boundary is crossed. IOW, MMW tags behave like the
Word file, and not like the Word-filter imported text.

* We are doing everything we can to shoehorn Word's 50 tabs into
Quark's 20 slots. The sequence for an exception is delete, compact,
add, sort, compact, with the whole point being never to waste a
slot. Word's (wonderful!) vertical line tab is omitted, of course.
But, at bottom, when we get to the 21st tab, we're done - the rest
are tossed.

* It's _real_ fast... (grin)



6. Mark My Words in real life...

The mis-selection business works like this: before we apply any
styling, we are looking at the raw text. Where we spot an open
angle bracket, we are looking ahead to see if it is legally
terminated. If it isn't we are insulating it as "<\<>" (the XPress
tags way of showing an open bracket as text). We are doing the same
thing for illegal closing angle brackets ("<\>>"). That way, we can
be assured that every angle bracket found in the text is part of a
legal XPress tag. Then, when we get around to looking for
improperly nested tags (e.g., <I<B>>, as shown above), we can
easily switch things around without worrying that we're hosing good
text.

Important: the MMW tag insulation is not as good as XP8's. We're
not striving to identify improperly formatted tags, but, rather, to
insulate the genuine impostors. Likewise: unlike XP8, we are not
doing anything about "@" and "\" when they are used as text.
Properly, these should be shown as <\@> and <\\>. To be safe(r),
you should still run the MMW file through XP8. Then use Xtags, of
course, since, while XPress tags filter 1.6 will be a lot better
about this than 1.5, Xtags' error-reporting still blows it out of
the water.

Moreover, you are ever and always on your own when it comes to tags
that are legal but illogical. If you have this as text:

<<B>>

Mark My Words will know enough to make it look like legal XPress
tags (<\<><B><\>>), but that <B> in the middle is legal and will
pass the test of quality in MMW, in XP8, in XPress tags and in
Xtags. Everything after it will be bold until it is turned off. In
other words: while software can protect you from obvious,
identifiable errors, it can never be a substitute for an active
human intelligence.

On the same planet: if you have a file (like this one) that is
filled with clearly legal XPress Tags that are _not_ intended to be
interpreted as XPress Tags, you need to insulate them on your own,
since no software is going to reject perfectly legal tags. You can
search for, e.g., "<" and replace with "<\<>", but that seems to me
to beg for errors. What I do is this: I search for "<" and replace
with "«" (option-backslash; closing form is
shift-option-backslash). That keeps approximately the same look,
and it's easy enough to switch back when I get to XPress. The point
is this: if it's not to be interpreted as a tag, it can't _look_
like a legal tag.

Next up: Xtags looks for pictures only by absolute path (like
Quark). I omitted paths in the picture specifications so you
_could_ move the pics if you wanted; otherwise Xtags would insist
they remain where birthed, and Quark would still only let you move
them into the same folder as the Quark file without relinking.
Ergo, move a standing Quark file or Save a new file into the folder
where the pictures reside prior to doing Get Text With Xtags.

IMPORTANT (and easy to forget): If the Quark file and the pictures
are not resident in the same folder, Xtags won't find them.

On the point: those Xtags text and picture boxes are cool, but each
one is a Quark object. That means that each one takes time to
create, and more time, ever and always, for Quark to manage. A word
to the wise is sufficient: if you create a file with thousands of
objects, expect to do a lot of waiting...

And: if you don't have an Xtags translate table, delete the text
for it in in Ancillary coding and Save Prefs. If no text, no tag. I
myself have a table named "YourTableName" (grin - but I'm not
kidding).

Mark My Words will not process Fast Saved files. Sorry. We had
wanted to do it with this version, but I deliberately walked away
from it because Word files are entirely too attenuated as it is. If
you select or D&D a Fast Saved file, MMW will display an Alert then
get on to the next task.

There are a certain few other occasions where Mark My Words will
fail (ever gracefully) to process a file. For example, files
produced by versions of Word earlier than 4.0 are politely refused.
And: files that are excessively complicated are deflected. In the
former event, open the file from Word and Save As in a version less
historic. In the latter case, chop the file up into smaller chunks
and feed them to MMW in a batch. For reference: a file will be
refused on the grounds of complexity if it entails more than 8192
character styling or 8192 paragraph styling changes. This limit is
eight times that imposed by WordLess Plus, and you may be delighted
to hear that we haven't been able to hit it in extremely
complicated testing files weighing in at over a quarter-megabyte.
In other words, complexity is a non-issue.

Real life: Word plus Mark My Words make a better front end to Quark
than anything we now have available. In the long run, I intend to
make something better, but this will do for now. The advantages are
these: You can draft as Styled Text, using the familiar Keyboard
Equivalents, as opposed to typing verbose and obscure XPress Tags.
Moreover, the people who type for you can give you what you need
without your having to teach them very much. The resultant files
can be run through Mark My Words, Torquemada, and XP8. And then, if
you want, you can open them _again_ from Word, do the edits as
Styled Text, run through Mark My Words again, etc. You can work
with tags without having to type (and _check!_) each and every one.

If you are lucky enough to have people typing for you who do what
you say, you can introduce their files to Torquemada and have a
great deal of the up-front labor of your jobs done for free. For
example, if some words of a paragraph need to swap out to a PMS
color, you can have the keyboarder style that text as "Blue", then
search in Torquemada, replacing "Blue" with the true name of the
color. Or you can use XP8's mnemonics or a code of your own
devising to flag special situations and dingbat characters, then
use XP8 or Torquemada to plug in the true XPress Tags coding.

Unless you turn this feature off, every Mark My Words file begins
with the XPress Tags version tag ("<v1.60><e0>"). This is included
because Mark My Words makes use of the Baseline Shift tag
("<bXX>"), and Quark varies its interpretation of that tag based on
the presence or absence of the version tag. Without it, the file is
interpreted as being a Quark 3.0 file, and the effect of the
Baseline Shift is inverted (viz., positive values shift down
instead of up, replicating a bug in the XPress Tags filter that
shipped with Quark 3.0). If you are still running XPress 3.0
(why?), you will need to do two things: lose the version tag and
invert the signs of all baseline shifts. These Torquemada strings
should serve to do both:

<v^?^p        {nothing}        Omit the version tag

-b^#        |b^#            Mark the negative values

b^#            -b^#            Invert the positive values

|-            {nothing}        Remove the marks

In the same neighborhood: the second half of the version tag
("<e0>") is a language identifier. If you are working with a
non-English version of Quark, you may need to change this to the
code shown when you Save Text as XPress Tags from within Quark.

Likewise: we are converting the QuickDraw colors in Word using
their English names (e.g., "Black", "Blue"). I don't know if
non-English versions of Quark tags use non-English names for the
QuickDraw colors, but, if they do, and if you're competent with
ResEdit, you can "internationalize" these colors fairly simply by
editing STR# resource number 133. Change only the literal name of
the color, leaving the quote marks alone. Sequence is significant,
so translate the color names "in place" (e.g., "Schwarz" for
"Black", not "Blue"). If you work in multiple languages, you can
spawn versions of MMW, one for each language you use. Presumably,
nothing else about XPress tags is language-sensitive, but if that
turns out not to be the case, do please let me know. We strive to
make our software as international as possible, and we fail through
ignorance rather than lack of trying.

And one more: as a default, we are showing Word's numbered
footnotes in Quark's Superior style. Alas, there is no clear-cut
way of dealing with footnotes flagged manually with user-supplied
text. These are being shown the way that Word is storing them. For
example, they might come across as "<z9.0b3.0>". If you have
footnotes of both types in the same file, you'll need to search to
bring them into concordance.

Useful: Word 5.x does an excellent job of filtering a number of
alien file formats. It sees all its own historical versions, of
course, plus all of the many version of DOS Word. But it also does
a great job with, e.g., WordPerfect for Mac and DOS. The best thing
to do with an alien file is to get it into Word in some way,
preferably from Word 5.x, from MacLink or Software Bridge
otherwise. Then Save As a Word 5.x file and run the resultant file
through Mark My Words. This is the most efficient means you have of
retaining the maximum amount of supplied paragraph and character
formatting.

Eminently nerd-like hack: every piece of software by me that has a
Preferences menu (Shane the Plane, Clip 'n' Save, ShawBerry, and
Mark My Words) stores its preferences in the resource fork of the
software itself. The Default prefs are stored in 'PREF' resource
128, and the Saved prefs are stored in PREF 129. When you Save
preferences, PREF 129 is re-written with your new settings. If you
are comfortable with ResEdit, you can use it to give yourself two
sets of stored preferences. Do this (on a _copy_ of Mark My Words,
of course):

1. Establish your second-favorite settings and Save preferences.
Quit.

2. Open the copy of Mark My Words from ResEdit, and navigate your
way to PREF 129. Select all and Copy.

3. Open PREF 128, Select All and Paste. Save and Close the file.
The two resources are now identical, with both containing your
second-favorite settings.

4. Launch Mark My Words again and establish your (first-)favorite
settings and Save preferences. Now when you do Restore defaults,
you'll get your second-favorite settings, and when you do Restore
saved prefs, you'll get your (first-)favorite settings, which will
also be loaded automatically with every subsequent launch.



7. About Greg Swann...

Okay, here's the deal: I'm not just a developer, I'm a user of
software as well. I make about half of my money doing Desktop
Publishing. In consequence, I have a pretty clear idea of how to
focus utilities designed to plug gaps in the functionality of major
applications. I am quite sure there are a _lot_ of developers
brighter than I am. But the evidence of experience suggests that
few of them have my advantage of living on both sides of the line,
so to speak.

What does this mean?

First, it means that I have written a _lot_ of mission-critical
utilities in support of the software categories of interest to me:
file management, font management, automated text processing,
PostScript-processing, and automated DTP-software preparation. All
but four of these utilities are FreeWare (the exceptions being Mark
My Words and the three packages discussed below) and are available
on CompuServe (GO DTPForum, BROwse on 70640,1574) and other
electronic information services (including any service offering
access to the Arizona Macintosh User's Group BBS-In-A-Box CD-ROM).

Second, it means that if you are likewise interested in these
software categories, it behooves you to support my work. Fanmail is
always nice, of course, but remuneration is the sincerest form of
flattery (grin). Seriously: this is a business, even if a
microscopically small one. It has been worthwhile so far because
the other things commanding my attention have not been as
lucrative. But that is changing (of course, and obviously,
_because_ of all the software). I can make a _lot_ of money writing
custom software for contracted clients. And I can streamline my own
production work without having to monkey-proof and document my
tools. So: if I am to keep doing this, I have to make it pay. If
you _want_ me to keep doing it, you have to pay me. It's that
simple.

In many ways, retail software is simpler. You pay or you don't
play, and no one has any illusions. The difference is, the
developer needs a _much_ larger capital commitment, and he needs to
surround himself with babbling morons in suits who might - just
possibly - be good for something other than chuckling about
football. Electronically distributed software gets around that
trap, but introduces the problem exposed here: the ambiguity of the
sales transaction results in a lot of prostrate begging by
developers. I don't beg, but I don't work for free except on my own
terms for my own good reasons.

There are three possible "futures" for authors of electronically
distributed software. 1. The rewards do not justify the effort, so
the author goes and plays tennis or something. 2. The author
produces software as an after-work hobby and continues to do so
more or less irrespective of user-response (some of the best and
worst FreeWare comes out of this category). 3. The author's growing
reputation results in him getting more contracted custom
programming work, worth more money, to the point that he no longer
has time to produce electronically distributed software.

It is the last that is happening to me, and this is why you need to
support my work, if you want it to continue. I'll do all right
whether I'm working on problems that confront you or on the
problems of some corporation. But: if you are using software by me
that has a commercial version (and all of them are discussed here),
and if you want me to _continue_ thinking about your problems,
rather than the problems of Consolidated MediCalc - you know what
to do...

These are my commercial programs (excluding Mark My Words, about
which you might already have heard a word or two (grin)):

XP8 - a very intelligent file filter that cleans up and makes the
filthiest text QuarkXPress-ready. Among many other features, it
offers DOS-file reformatting, financial-text clean-up, garbage
disposal, typographic quality enhancement, and the best quote
conversion we know of. The ShareWare version of XP8 (v1.0.0) can be
found on CIS, GO DTPForum, Library 5, under the name XP8.SEA. It is
also included on the distribution disk for the unrestricted version
of Mark My Words. The current commercial version is v1.0.6 and
offers a great many enhancements over the ShareWare version.

Torquemada The Inquisitor - batch global search and replace
software with wildcards, pattern matching, string substitution, et
very cetera. With Drag & Drop under System 7, you can run up to 640
searches on up to 128 files in one batch. Features the most
intelligent case-conversion we know of. The most-recent FreeWare
version (1.1.0) can be found on CIS, GO DTPForum, Library 5, under
the name TORQUE.SEA. It is also included on the distribution disk
for the unrestricted version of Mark My Words. The current
commercial version is 1.2.2, offering a great many enhancements,
including new "wildthings" and a _lot_ of new User Interface power.

Shane the Plane 2.0.0 - file and font attribute editing utility.
Interactively or in Drag & Drop batches, permits you to change the
Creator/Type of files, their created/modified dates and times, a
host of significant Finder flags, plus a lot more. Makes files
invisible/visible, makes fonts behave like files by removing their
BNDL resources, batch "pastes" custom icons, intelligently renames
and/or "slugs" files, et very cetera. A demonstration version
(fully functional but limited to 32 launches) can be found on CIS,
GO DTPForum, Library 12, under the name SPDEMO.SEA. It is also
included on the distribution disk for the unrestricted version of
Mark My Words.

(While I've vectored all the files toward CIS, my primary haunt,
they are also available on other services, and on any BBS which has
the most recent version of AMUG's BBS-In-A-Box CD-ROM on line.)

Shane the Plane 2.0.0 is sold on these terms:  (US)$40 each, per
license. Two to 10 licenses are $35 each, and 11 or more are $30
each.

Mark My Words, XP8 and Torquemada are each sold under these terms:
(US)$50 each, per license. Two to 10 licenses are $45 each, and 11
or more are $40 each. These three programs will eventually be
rolled into a stand-alone text editor cum word processor currently
in design with the working name "MyEditor". You will be entitled to
a 25% discount on the price of the MyEditor, when it is released,
for each of these utilities you have purchased and registered. In
other words, if you own XP8, your discount will be 25%. If you own
XP8 and Torquemada, it will be 50%. And if you own all three, you
will be entitled to a 75% discount. (This discount does not apply
to Shane the Plane, which is establishing its own upgrade path.)

If you want to buy any or all of these programs, send a check or
money order* to:

    Greg Swann
    P.O. Box 1724
    Andover, MA 01810

    or

    1331 West Baseline Road, #236
    Mesa, AZ 85202

*Outside the U.S., you may send cash at your own risk, if exchange
issues make that expedient.

These programs are included on the distribution disk for the
unrestricted version of Mark My Words:

* Mark My Words v1.0.0 - discussed here at some length (!)

* XP8 v1.0.0 - ShareWare version of the commercial software

* Torquemada the Inquisitor v1.1.0 - FreeWare version of the
  commercial software

* A Sort of a Kind - very fast, very robust text file sorting utility

* FontFischer - font specimen book creation utility

* PixPex - Drag & Drop Xtags picture box creation utility

* ShawBerry - text file merging utility

Plus some other stuff...



8. Conclusion...

Jeez, haven't you had _enough_...? (grin)

Seriously: that's it. If you have any questions or problems, the
easiest way to get hold of me is on CompuServe at 70640,1574
(Internet [e-mail]). If you can't do that, you can
snail mail me at:

    Greg Swann
    P.O. Box 1724
    Andover, MA 01810

    or

    1331 West Baseline Road, #236
    Mesa, AZ 85202

Why two addresses? The Arizona address will result in 2-3 days
faster turnaround. The P.O. Box in Massachusetts is still the
"official" address, because we'll be moving again within the year.
If we knew for sure we'd be buying a house in Mesa, we'd just get a
P.O. Box here. But since we could end up a fair distance from here,
we kept the Andover box on a forwarding basis, so as to avoid
either losing mail when a temporary forwarding order gives out or
driving a lot of miles just to pick up mail. Memo to USPS:
WATS-like mailing addresses would be way cool.

Last licks: it turns out that the Suns died in the NBA finals, so
now Barkley can rest. Miles to go before _I_ sleep, but this is a
big weight off my shoulders. Here's hoping it buys a nap or two
for you!